Documentation on cgdisp
Task: cgdisp
Purpose: Displays and overlays images on a PGPLOT device
Categories: plotting
CGDISP displays/overlays images via contour plots, pixel map
representations, vectors and scaled boxes on a PGPLOT device.
Upto 3 contour plots, one pixel map, one vector plot and one box
display may be overlaid in multi-panel plots of multi-channel
images. In addition overlay locations (plotted as boxes, stars,
circles, lines or see-through) may be specified from an ascii
text file.
Manipulation of the device colour lookup table is available
when you display with a pixel map representation (formerly
called a "grey scale")
Key: in
You may input up to 7 images. Upto 3 of these can be displayed
via contour plots and 1 can be displayed via a colour pixel map
representation. 1 vector amplitude image and 1 vector position
angle image (degrees; positive N - E) can together be used to
display a vector map (e.g. polarization vectors). 1 image can
be displayed as small scaled boxes (see below) and 1 image may be
used as a mask.
The "box" image is displayed by drawing little boxes (solid and
hollow for positive and negative pixels) at the location of each
selected pixel. The size of the box scales with the value of the
pixel. This is a useful way to display rotation measure images
for example. The mask image blanking mask is logically ORed to all
the other image masks before they are displayed. The mask image
is not displayed.
If more than one image is specified, they must have identical
first and second dimensions. However, you can overlay combinations
of 2-D with 3-D images (e.g. multi-channel images with a continuum
image) provided all the 3-D images have the same third dimension.
These images can be input in any order (see TYPE).
Wild card expansion is supported. No default.
Key: type
Specifies the type of each image, respectively, listed in the IN
keyword. Minimum match is supported (note that "pixel" was
formerly "grey" [which is still supported]). Choose from:
"contour" (contour; up to 3 of these)
"pixel" (pixel map; up to 1 of these)
"amplitude" (vector amplitude; up to 1 of these)
"angle" (vector pos'n angle; up to 1 of these)
"box" (box; up to 1 of these)
"mask" (mask; up to 1 of these)
You can't give one of "amplitude" or "angle" without the other.
Default is "pixel" for one image, "contour" if more than one.
Key: region
Region of interest. Choose only one spatial region (bounding box
only supported), but as many spectral regions (i.e., multiple
IMAGE specifications) as you like. Each channel (or group of
channels; see CHAN below) is drawn on a new sub-plot.
NOTE: the region specification applies equally to all the
input images.
Default is full image
Key: xybin
Upto 4 values. These give the spatial increment and binning
size in pixels for the x and y axes to be applied to the selected
region. If the binning size is not unity, it must equal the
increment. For example, to bin up the image by 4 pixels in
the x direction and to pick out every third pixel in the y
direction, set XYBIN=4,4,3,1
Defaults are 1,XYBIN(1),XYBIN(1),XYBIN(3)
Key: chan
2 values. The first is the channel increment to step through the
image in, the second is the number of channels to average, for
each sub-plot. Thus CHAN=5,3 would average groups of 3 channels
together, starting 5 channels apart such as: 1:3, 6:8, 11:13 ...
The channels available are those designated by the REGION keyword.
A new group of channels (sub-plot) is started if there is a
discontinuity in the REGION selected channels (such as
IMAGE(10,20),IMAGE(22,30). The combination of REGION and CHAN
determines how many sub-plots there will be.
In the case that you have input some combination of 2-D and 3-D
images, CHAN refers to the 3-D image(s). Note that a channel
is defined to be a pixel on the third axis of a cube, regardless
of the cube's order (xyv or vxy say).
Defaults are 1,1
Key: slev
Up to 3 pairs of values, one for contour image. First value is
the type of contour level scale factor. "p" for percentage and
"a" for absolute. Second value is the factor to scale LEVS by.
Thus, SLEV=p,1 would contour levels at LEVS * 1% of the image
peak intensity. Similarly, SLEV=a,1.4e-2 would contour levels
at LEVS * 1.4E-2
Default is no additional scaling of LEVS (i.e., "a",1.0)
Key: levs1
The levels to contour for the first specified contour image are
LEVS1 times SLEV (either percentage of the image peak or absolute).
Defaults try to choose something vaguely useful.
Key: levs2
LEVS for the second contour image.
Key: levs3
LEVS for the third contour image.
Key: range
N groups of 4 values (1 group per subplot and N is the maximum
number of channels allowed by Miriad; typically 2048). These are
the image intensity range to display (min to max), the transfer
function type and the colour lookup table for each subplot
displayed. The transfer function type can be one of "lin"
(linear), "sqr" (square root), "log" (logarithmic), and "heq"
(histogram equalization). The colour lookup table is an integer
from 1 to 8 specifying a lookup table. Valud values are 1 (b w),
2 (rainbow), 3 (linear pseudo colour), 4 (floating zero colour
contours), 5 (fixed zero colour contours), 6 (rgb), 7 (background)
8 (heat) and 9 (absolute b w) . If you enter a negative
integer, then the reversed lookup table is displayed.
The transfer function changes available with OPTIONS=FIDDLE
are in addition (on top of) to the selections here, but the
colour lookup table selections will replace those selected here.
All subplots following the last one with a specified "range"
will use the "range" settings from the previous subplot. In
this way, one group of settings can be applied to all the
subplots if desired. The multiple subplot capability is useful
if you have used IMCAT to put unlike images into planes of
a cube and you wish to display them together.
Default is linear between the image minimum and maximum with
a b w lookup table. You can default the intensity range with
zeros, viz. "range=0,0,log,-2" say.
Key: vecfac
3 values. A scale factor to multiply the vector image lengths
(or box image widths) by, and the x and y increments (in pixels)
across the image at which to plot the vectors (or boxes). If
you have set non unit values of XYBIN, the increments here refer
to the binned pixels. When VECFAC(1)=1, the vectors (boxes) are
scaled so that the maximum amplitude (width) takes 1/20 of the
(sub)plot size.
Defaults are 1.0, 2, VECFAC(2)
Key: boxfac
3 values. A scale factor to multiply the box image widths by,
and the x and y increments (in pixels) across the image at which
to plot the boxes). If have set non unit values of XYBIN, the
increments here refer to the binned pixels. When BOXFAC(1)=1,
the boxes are scaled so that there is a little bit of space
between adjacent boxes.
Defaults are 1.0, 2, BOXFAC(2)
Key: device
The PGPLOT plot device, such as plot.plt/ps
No default.
Key: nxy
Number of sub-plots in the x and y directions on the page.
Defaults choose something depending on your telescope.
Key: labtyp
Up to 2 values. The spatial label type of the x and y axes.
Minimum match is active. Select from:
"hms" the label is in H M S.S (e.g. for RA)
"dms" the label is in D M S.S (e.g. for DEC)
"arcsec" the label is in arcsecond offsets
"arcmin" the label is in arcminute offsets
"absdeg" the label is in degrees
"reldeg" the label is in degree offsets
The above assume the pixel increment is in radians.
"abspix" the label is in pixels
"relpix" the label is in pixel offsets
"abskms" the label is in Km/s
"relkms" the label is in Km/s offsets
"absghz" the label is in GHz
"relghz" the label is in GHz offsets
"absnat" the label is in natural coordinates as defined by
the header.
"relnat" the label is in offset natural coordinates
"none" no label and no numbers or ticks on the axis
All offsets are from the reference pixel.
Defaults are "relpix", LABTYP(1) except if LABTYP(1)="hms" when
LABTYP(2) defaults to "dms" (to give RA and DEC)
Key: options
Task enrichment options. Minimum match of all keywords is active.
"abut" means don't leave any white space between subplots. The
default is to leave a little bit between subplots, and
OPTIONS=GAPS leaves a lot of space and labels eacg subplot
separately.
"beamAB", where "A" is one of "b" or "t" and
"B" is one of "l" or "r"
means draw the beam FWHM on the plot in the corner indicated
by the "AB" location. The beams for all images displayed
(contour and pixel map) will be drawn confocally. If you want
to draw the beam somewhere else, you could use the "ellipse"
overlay type (see keyword OLAY).
"conlabel" means label the contour values on the actual contours.
The PGPLOT routine that does this is not very bright. You will
probably get too many labels. If you bin the image up with
keyword XYBIN, say, by a factor of 2, you will get about 1/2
as many labels. If desperate use the overlay facility
(keyword OLAY) to manually label contours.
"fiddle" means enter a routine to allow you to interactively change
the display lookup table. You can cycle through a variety of
colour lookup tables, as well as alter a linear transfer function
by the cursor location, or by selecting predefined transfer
functions (linear, square root, logarithmic, histogram equalization)
For hard copy devices (e.g. postscript), a keyboard driven
fiddle is offered; you can cycle through different colour tables
and invoke the predefined transfer functions, but the linear
fiddler is not available. Note that if you are using "cgdisp"
from a script, so that interactive fiddling is not appropriate,
you can use the "range" keyword to specify the transfer
function and colour lookup tables.
"full" means do full plot annotation with contour levels, pixel
displa range, file names, reference values, etc. Otherwise
more room for the plot is available.
"gaps" means leave large gaps between subplots and individually
label the axes of each subplot. By default, the subplots will
have a small amount of white space between each subplot and
they will only be labelled around the borders of the full page.
See also OPTIONS=ABUT to eliminate the small amount of white space.
"grid" means draw a coordinate grid on the plot rather than just ticks
"mirror" causes all specified contour levels for all images
to be multiplied by -1 and added to the list of contours
"nodistort" means that angularly-defined overlays do not distort
with the coordinate grid. If you are displaying a large area of
the sky, such that the non-linearities in the coordinate system
can be seen, then by default, the overlays (keyword OLAY) will
distort with the coordinate grid if you are using angular units
for the overlay locations and half sizes. Thus star overlays
will rotate and stretch, circles will distort similarly.
Overlays given in non-angular units will always be undistorted.
"noepoch" means don't write the epoch value into the axis labels
"noerase" means don't erase a rectangle into which the "3-axis"
values and the overlay ID strings are written.
"nofirst" means don't write the first x-axis label on any subplots
except for the left-most one. This may avoid label overwrite.
"relax" means issue warnings when image axis descriptors are
inconsistent (e.g. different pixel increments) instead
of a fatal error. Use at your peril.
"rot90" rotates vectors by an extra 90 degrees. Useful
to convert E-vectors into B-vectors
"signs" Normally, when plotting vectors, CGDISP assumes that
North is up and East to the left. If OPTIONS=SIGNS, then
it assumes that E and N are in the direction of increasing
X and Y.
"single" means that when you have selected OPTIONS=FIDDLE and you
you have more than one subplot per page, activate the fiddle
option after each subplot rather than the default, which is
to fiddle only at the end. In the latter case, the histogram
equalization, if invoked, will have been computed with the
image in the last subplot only.
"solneg1" means make negative contours solid and positive
contours dashed for the first contour image. The default,
and usual convention is the reverse.
"solneg2" SOLNEG1 for the second contour image.
"solneg3" SOLNEG1 for the third contour image.
"trlab" means label the top and right axes as well as the
bottom and left ones. This can be useful when non-linear
coordinate variation across the field makes the ticks misaligned
"unequal" means draw plots with unequal scales in x and y
so that the plot surface is maximally filled. The default
is for equal scales in x and y.
"wedge" means that if you are drawing a pixel map, also draw
and label a wedge to the right of the plot, showing the map
of intensity to colour.
"3pixel" means label each sub-plot with the pixel value of
the third axis.
"3value" means label each sub-plot with the appropriate
value of the third axis (e.g. velocity or frequency for an
xyv ordered cube, position for a vxy ordered cube).
Both "3pixel" and "3value" can appear, and both will be
written on the plot. They are the average values when
the third axis is binned up with CHAN. If the third axis
is not velocity or frequency, the units type for "3VALUE"
will be chosen to be the complement of any like axis in the
first 2. E.g., the cube is in vxy order and LABTYP=ABSKMS,ARCSEC
the units for the "3VALUE" label will be arcsec. If
LABTYP=ABSKMS,HMS the "3VALUE" label will be DMS (if the
third [y] axis is declination).
Key: lines
Up to 6 values. The line widths for the axes, each contour
image (in the order of TYPE), the vector image, and any overlays.
If there are less than 3 contour images or no vector
image, the vector image/overlay line widths shift left.
Line widths must be integers.
Defaults are 1,1,1,1,1,1
Key: break
Up to 3 values. The intensity levels for the break between
solid and dashed contours for each contour image.
Defaults are 0.0,0.0,0.0
Key: csize
Up to 4 values. Character sizes in units of the PGPLOT default
(which is ~ 1/40 of the view surface height) for the plot axis
labels, the velocity/channel label, the overlay ID string
(if option "write" in OLAY used) label, and the contour
value labels (see options=conlab).
Defaults try to choose something sensible. Use 0.0 to default
any particular value. E.g., 1.4, 0, 0, 0.5
Key: scale
Up to 2 values. Scales in natural axis units/mm with which to plot
in the x and y directions. For example, if the increments
per pixel are in radians, then this number would be radians/mm
(note that for RA axes you give radians on the sky per mm).
Although this choice of unit may be cumbersome, it makes no
assumptions about the axis type, so is more flexible. If you
also chose OPTIONS=EQUAL then one of your scales, if you set
both and differently, would be over-ruled. If you give only
one value, the second defaults to that.
Defaults choose scales to fill the page optimally. To default
the first but the second, use 0.0,scale(2)
Key: olay
The name of a file containing a list of overlay descriptions.
Wild card expansion is active and the default is no overlays.
Miriad task CGCURS OPTIONS=CURSOR,LOG,CGDISP can be used to
make an overlay file.
Entries in the overlay file can be white space or comma
delimitered or both. All lines beginning with # are ignored.
**** DO NOT USE TABS ****
Double quotes " are used below to indicate a string. The "
should not be put in the file. For all the string parameters
discussed below, you can abbreviate them with minimum match.
Each line describes an overlay and should be as follows:
##### The first 5 columns in each line must be
1 2 3 4 5 Column
--------------------------------
OFIG XOTYPE YOTYPE ID WRITE where
OFIG is the type of overlay; choose from
"star" for stars (crosses; give centre and half-sizes)
"circle" for a filled in circle (give centre and radius)
"ocircle" for an open circle (give centre and radius)
"ellipse" for a filled in ellipse (give centre, half axes and p.a.)
"oellipse for an open ellipse (give centre, half axes and p.a.)
"box" for boxes (give centre and half-sizes)
line for line segments (give ends)
"clear" for a see-through overlay -- thus you can write the
overlay ID string (see below) without the overlay
XOTYPE and YOTYPE give the units of the overlay location (and
overlay half-sizes) contained in the file for the x- and y-
directions, respectively. Choose from:
"hms", "dms", "arcsec", "arcmin", "absdeg", "reldeg", "abspix",
"relpix", "absnat", "relnat", "absghz", "relghz",
"abskms", "relkms" as described in the keyword LABTYP.
Note that OTYPE does not depend upon what you specified for LABTYP.
ID is an identifying overlay string which can be optionally
written on the overlay; it MUST be in the overlay file whether
you write it on the plot or not). The ID string is written in the
corner for "star" and "box", in the centre for "clear", "circle"
at the end for line. Note that the underscore character "_"
is treated a special case and is replaced by a blank before plotting.
In this way, you can write several words as the overlay ID; you
connect them with underscores in the overlay file, and cgdisp
strips them out before plotting.
WRITE is "yes" or "no" to specify if the overlay ID is to be
written in the overlay figure or not.
##### Columns beyond number 5 depend upon OFIG, XOTYPE, and YOTYPE
6 7 8 9 10 11 12 Logical column
---------------------------
X Y XS YS CS CE for OFIG="box" and "star"
X1 Y1 X2 Y2 CS CE for OFIG=line
X Y R CS CE for "circle" and "ocircle"
X Y R1 R2 PA CS CE for "ellipse" and "oellipse"
X Y CS CE for OFIG="clear"
X,Y defines the center of the overlay in the nominated OTYPE
coordinate system (X- and Y-OTYPE can be different).
(X1,Y1) (X2,Y2) are the end points of the line segment in the
nominated OTYPE (mixed OTYPEs are supported here too).
For %OTYPE = "abspix ", "relpix", "arcsec", "arcmin", "absdeg",
"reldeg", "absghz", "relghz", "abskms", "relkms",
"absnat" "relnat" X,Y,X1,Y1,X2,Y2 are single numbers.
For %OTYPE = "hms" or "dms", the X and/or Y location is/are replaced
by three numbers such as HH MM SS.S or DD MM SS.S. Thus if
XOTYPE=hms YOTYPE=dms then the file should have lines like
HH MM SS.S DD MM SS.S XS YS CHAN for OFIG="box", say
XS, YS are the overlay half-sizes in the following units.
%OTYPE = "abspix" and "relpix" in pixels
"hms" and "dms" in arcseconds
"arcsec" in arcseconds
"arcmin" in arcminutes
"absdeg" and "reldeg" in degrees
"absghz" and "relghz" in GHz
"abskms" and "relkms" in Km/s
"absnat" and "relnat" in natural coordinates
R is the radius of circle overlays. It is in the units given
in the above list according to XOTYPE only.
R1 and R2 are the ellipse major and minor axes half-widths,
both in units according to XOTYPE. PA is the position angle
in degrees, positive N - E
CS to CE is the channel range (image planes) on which to put the
overlays. If you specify only CS than the overlay is put
on that channel. If CS=0 then the overlays are put on all
channels.
For OFIG="box" and "star", XS, YS are optional. The defaults
are XS=2, YS=XS pixels. In all cases, CS and CE are optional
and the default is 0 (all channels)
##### The OFFSET line
At any point in the overlay file, you can include an OFFSET
line in the format
"OFFSET" XOFF YOFF
where the literal "OFFSET" (without the quotes) must appear
as the first thing in the line, followed by X and Y offsets,
which are applied to all succeeding overlay file locations.
X = X + XOFF; Y = Y + YOFF
These offsets must be in the same units as the %OTYPE that the
succeeding line(s) has(ve). It is intended so that your overlay
locations can be in, say, arcsec relative to some location which
is not the reference pixel of the image (which is what CGDISP
ultimately wants). You then specify, with the OFFSET line, the
offsets between the reference pixel of the contour/pixel map
images and the actual reference location of your overlay locations.
You can have as many OFFSET lines as you like in the file. All
succeeding lines will apply these offsets until new ones are
defined. If the line does not appear, naturally no additional
offsets are added.
The OFFSET line is not applied to ANY position fields in succeeding
lines that have %OTYPEs that are "hms" or "dms". I am too lazy
to code it.
Generated by rsault@atnf.csiro.au on 11 Jul 1996